home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / asl.doc < prev    next >
Encoding:
Text File  |  1999-10-22  |  34.1 KB  |  934 lines
  1. TABLE OF CONTENTS
  2.  
  3. asl.library/AbortAslRequest
  4. asl.library/ActivateAslRequest
  5. asl.library/AllocAslRequest
  6. asl.library/AllocFileRequest
  7. asl.library/AslRequest
  8. asl.library/FreeAslRequest
  9. asl.library/FreeFileRequest
  10. asl.library/RequestFile
  11. asl.library/AbortAslRequest                       asl.library/AbortAslRequest
  12.  
  13.    NAME
  14.     AbortAslRequest -- attempt to abort an asl requester. (V44)
  15.  
  16.    SYNOPSIS
  17.     AbortAslRequest(requester);
  18.                        A0
  19.  
  20.     VOID AbortAslRequest(APTR requester);
  21.  
  22.    FUNCTION
  23.     The different types of asl requesters are modal (as of V44). Yet at
  24.     times it may be necessary to abort a modal requester from a different
  25.     task context. AbortAslRequest() will attempt to tell the modal asl
  26.     requester provided to shut down and perform as if the user had clicked
  27.     on the requester's window close gadget. This may take some time to
  28.     complete; be prepared to handle this.
  29.  
  30.    INPUTS
  31.     requester - requester obtained from AllocAslRequest(), or NULL in
  32.             which case this function does nothing.
  33.  
  34.    SEE ALSO
  35.     AslRequest()
  36.  
  37. asl.library/ActivateAslRequest                 asl.library/ActivateAslRequest
  38.  
  39.    NAME
  40.     ActivateAslRequest -- attempt to activate an asl requester. (V44)
  41.  
  42.    SYNOPSIS
  43.     ActivateAslRequest(requester);
  44.                           A0
  45.  
  46.     VOID ActivateAslRequest(APTR requester);
  47.  
  48.    FUNCTION
  49.     The different types of asl requesters are modal (as of V44). Yet at
  50.     times it may be necessary to activate a modal requester from a different
  51.     task context.
  52.  
  53.    INPUTS
  54.     requester - requester obtained from AllocAslRequest(), or NULL in
  55.             which case this function does nothing.
  56.  
  57.    SEE ALSO
  58.     AslRequest()
  59.  
  60. asl.library/AllocAslRequest                       asl.library/AllocAslRequest
  61.  
  62.    NAME
  63.     AllocAslRequest -- allocate an ASL requester. (V36)
  64.     AllocAslRequestTags -- varargs stub for AllocAslRequest(). (V36)
  65.  
  66.    SYNOPSIS
  67.     requester = AllocAslRequest(reqType,tagList);
  68.     D0                          D0      A0
  69.  
  70.     APTR AllocAslRequest(ULONG,struct TagItem *);
  71.  
  72.     requester = AllocAslRequestTags(reqType,firstTag, ...);
  73.  
  74.     APTR AllocAslRequestTags(ULONG,Tag,...);
  75.  
  76.    FUNCTION
  77.     Allocates an ASL requester data structure of the specified type.
  78.  
  79.    INPUTS
  80.     type - type of requester to allocate. Currently defined types
  81.            are ASL_FileRequest, ASL_FontRequest and ASL_ScreenModeRequest.
  82.            ASL_ScreenModeRequest is available starting with asl.library
  83.            V38 only.
  84.     tags - pointer to an optional tag list specifying how to initialize the
  85.            data structure returned by this function. See the
  86.            documentation for AslRequest() for an explanation of
  87.            how to use the currently defined tags.
  88.  
  89.    RESULT
  90.     requester - an initialized requester data structure, or NULL on
  91.                 failure. The data structure returned corresponds to the
  92.             requested type;
  93.             ASL_FileRequest       -> (struct FileRequester *)
  94.             ASL_FontRequest       -> (struct FontRequester *)
  95.             ASL_ScreenModeRequest -> (struct ScreenModeRequester *)
  96.  
  97.    WARNING
  98.     All ASL requester data structures are READ-ONLY and can only be
  99.     modified by using tags!
  100.  
  101.     You must not specify requester options by using both pre-V38
  102.     tags like ASLFR_Flags1 and V38 tags like ASLFR_DoSaveMode as
  103.     this can lead to unexpected results.
  104.  
  105.     Take care when attaching an ASL requester to a simple refresh
  106.     window or a window that already shares its IDCMP with other
  107.     windows. In such cases you must ask for the ASL requester to
  108.     allocate a private IDCMP (with the ASLFR_PrivateIDCMP,
  109.     ASLFO_PrivateIDCMP and ASLSM_PrivateIDCMP tags) or your window
  110.     will lose IDCMP_REFRESHWINDOW events and other messages.
  111.  
  112.    BUGS
  113.     Under V38 and V39, the filtering functions for the file requester
  114.     were only asked to filter drawer selections if the ASLFR_FilterDrawers
  115.     tag was set to TRUE. The compatible behavior, reestablished in V40,
  116.     is to always pass drawers for filtering.
  117.  
  118.    NOTES
  119.     As of V38-V40 the ASL requester uses gadtools.library routines to
  120.     create and maintain its user interface. Every IntuiMessage the library
  121.     passes through the functions specified with ASLSM_IntuiMsgFunc and
  122.     ASLSM_HookFunc will have been filtered through the
  123.     gadtools.library/GT_GetIMsg() routine.
  124.  
  125.    SEE ALSO
  126.     AslRequest(), FreeAslRequest()
  127.  
  128. asl.library/AllocFileRequest                     asl.library/AllocFileRequest
  129.  
  130.    NAME
  131.     AllocFileRequest -- allocates an ASL FileRequester structure. (V36)
  132.  
  133.    SYNOPSIS
  134.     requester = AllocFileRequest()
  135.     D0
  136.  
  137.     struct FileRequester *AllocFileRequest(VOID);
  138.  
  139.    NOTES
  140.     This function is obsolete, please use AllocAslRequest() instead.
  141.  
  142.    SEE ALSO
  143.     AllocAslRequest()
  144.  
  145. asl.library/AslRequest                                 asl.library/AslRequest
  146.  
  147.    NAME
  148.     AslRequest -- get input from user using an ASL requester. (V36)
  149.     AslRequestTags -- varargs stub for AslRequest(). (V36)
  150.  
  151.    SYNOPSIS
  152.     result = AslRequest(requester,tags);
  153.     D0                  A0        A1
  154.  
  155.     BOOL AslRequest(APTR,struct TagItem *);
  156.  
  157.     result = AslRequestTags(requester,firstTag,...);
  158.  
  159.     BOOL AslRequestTags(APTR,Tag,...);
  160.  
  161.    FUNCTION
  162.     Prompts the user for input, based on the specific type of
  163.     requester and modifying tags. The actions and results
  164.     are specific to the type of requester, but in general the action is
  165.     to open a requesting window prompting the user for a specific input.
  166.     If the user cancels or the system aborts the request, FALSE
  167.     is returned, otherwise the requester's data structure reflects the
  168.     user input.
  169.  
  170.     Note that tag values stay in effect for each use of the
  171.     requester until they are cleared or modified by passing the
  172.     same tag with a new value.
  173.  
  174.    INPUTS
  175.     requester - requester structure allocated with AllocAslRequest(). If
  176.             this parameter is NULL, this function will always return
  177.             FALSE with a dos.library/IoErr() result of
  178.             ERROR_NO_FREE_STORE.
  179.     tags - pointer to an optional tag list which may be used to
  180.            control features of the requester.
  181.  
  182.    TAGS
  183.     Tags for use with the file requester:
  184.  
  185.     ASLFR_Window (struct Window *) - Parent window of requester. If no
  186.             ASLFR_Screen tag is specified, the window structure
  187.             is used to determine on which screen to open the
  188.             requesting window. (V36)
  189.  
  190.     ASLFR_PubScreenName (STRPTR) - Name of a public screen to open on.
  191.             This overrides the screen used by ASLFR_Window. (V38)
  192.  
  193.     ASLFR_Screen (struct Screen *) - Screen on which to open the requester.
  194.             This overrides the screen used by ASLFR_Window or by
  195.             ASLFR_PubScreenName. (V38)
  196.  
  197.     ASLFR_PrivateIDCMP (BOOL) - When set to TRUE, this tells ASL to
  198.             allocate a new IDCMP port for the requesting window.
  199.             If not specified or set to FALSE, and if ASLFR_Window
  200.             is provided, the requesting window will share
  201.             ASLFR_Window's IDCMP port. (V38)
  202.  
  203.     ASLFR_IntuiMsgFunc (struct Hook *) - A function to call whenever an
  204.             unknown Intuition message arrives at the message port
  205.             being used by the requesting window. The function
  206.             receives the following parameters:
  207.                 A0 - (struct Hook *)
  208.                 A1 - (struct IntuiMessage *)
  209.                 A2 - (struct FileRequester *)
  210.             (V38)
  211.  
  212.     ASLFR_SleepWindow (BOOL) - When set to TRUE, this tag will cause the
  213.             window specified by ASLFR_Window to be "put to
  214.             sleep". That is, a busy pointer will be displayed in
  215.             the parent window, and no gadget or menu activity will
  216.             be allowed. This is done by opening an invisible
  217.             Intuition Requester in the parent window. (V38)
  218.  
  219.     ASLFR_UserData (APTR) - A 32-bit value that is simply copied in the
  220.             fr_UserData field of the requester structure. (V38)
  221.  
  222.     ASLFR_TextAttr (struct TextAttr *) - Font to be used for the requesting
  223.             window's gadgets and menus. If this tag is not provided
  224.             or its value is NULL, the default font of the screen
  225.             on which the requesting window opens will be used.
  226.             This font must already be in memory as ASL calls
  227.             OpenFont() and not OpenDiskFont(). As of V38, the font
  228.             used in the file requester's file list must be
  229.             monospaced. If the font provided with this tag is
  230.             not monospaced, then the file list will use the current
  231.             system default font as chosen in preferences. (V38)
  232.  
  233.     ASLFR_Locale (struct Locale *) - Locale to use for the requesting
  234.             window. This determines the language used for the
  235.             requester's gadgets and menus. If this tag is not
  236.             provided or its value is NULL, the system's current
  237.             default locale will be used. As of V38, items such as
  238.             the date format always uses the system default locale.
  239.             (V38)
  240.  
  241.     ASLFR_TitleText (STRPTR) - Title to use for the requesting window.
  242.             Default is no title. (V36)
  243.  
  244.     ASLFR_PositiveText (STRPTR) - Label of the positive gadget in the
  245.             requester. English default is "OK". Prior to V38, this
  246.             string could not be longer than 6 characters. (V36)
  247.  
  248.     ASLFR_NegativeText (STRPTR) - Label of the negative gadget in the
  249.             requester. English default is "Cancel". Prior to V38,
  250.             this string could not be longer than 6 characters.
  251.             (V36)
  252.  
  253.     ASLFR_InitialLeftEdge (WORD) - Suggested left edge of requesting
  254.             window. (V36)
  255.  
  256.     ASLFR_InitialTopEdge (WORD) - Suggested top edge of requesting
  257.             window. (V36)
  258.  
  259.     ASLFR_InitialWidth (WORD) - Suggested width of requesting window. (V36)
  260.  
  261.     ASLFR_InitialHeight (WORD) - Suggested height of requesting window.
  262.             (V36)
  263.  
  264.     ASLFR_InitialFile (STRPTR) - Initial contents of the file requester's
  265.             File text gadget. Default is empty. (V36)
  266.  
  267.     ASLFR_InitialDrawer (STRPTR) - Initial contents of the file
  268.             requester's Drawer text gadget. Default is empty. (V36)
  269.  
  270.     ASLFR_InitialPattern (STRPTR) - Initial contents of the file
  271.             requester's Pattern text gadget. Default is #?. (V36)
  272.  
  273.     ASLFR_InitialShowVolumes (BOOL) - When opening the file requester,
  274.             read the list of active volumes, do not read the contents
  275.             of the specified drawer. (V44)
  276.  
  277.     ASLFR_Flags1 (ULONG) - Bulk initialization of many of the requester's
  278.             options. See <libraries/asl.h> for the possible
  279.             flag values. Default is 0. (V36)
  280.  
  281.     ASLFR_Flags2 (ULONG) - Bulk initialization of many of the requester's
  282.             options. See <libraries/asl.h> for the possible
  283.             flag values. Default is 0. (V36)
  284.  
  285.     ASLFR_DoSaveMode (BOOL) - Set this tag to TRUE when the file requester
  286.             is being used for saving. Default is FALSE. (V38)
  287.  
  288.     ASLFR_DoMultiSelect (BOOL) - Set this tag to TRUE to let the user
  289.             select multiple files at once. This tag excludes
  290.             save mode. Default is FALSE. (V38)
  291.  
  292.     ASLFR_DoPatterns (BOOL) - Set this tag to TRUE to cause a pattern
  293.             gadget to be displayed. Default is FALSE. (V38)
  294.  
  295.     ASLFR_DrawersOnly (BOOL) - Set this tag to TRUE to cause the requester
  296.             to only display drawers, and have no File gadget. This
  297.             is useful to let the user choose a destination
  298.             directory. Default is FALSE. (V38)
  299.  
  300.     ASLFR_FilterFunc (struct Hook *) - A function to call for each file
  301.             encountered. If the function returns TRUE, the file is
  302.             included in the file list, otherwise it is rejected
  303.             and not displayed. The function receives the following
  304.             parameters:
  305.                 A0 - (struct Hook *)
  306.                 A1 - (struct AnchorPath *)
  307.                 A2 - (struct FileRequester *)
  308.             (V38)
  309.  
  310.     ASLFR_RejectIcons (BOOL) - Set this tag to TRUE to cause the requester
  311.             not to display Workbench icons. This flag should
  312.             normally be set. Default is FALSE. (V38)
  313.  
  314.     ASLFR_RejectPattern (UBYTE *) - Specifies an AmigaDOS pattern that is
  315.             used to reject files. That is, any files with names
  316.             matching this pattern are not included in the file
  317.             list. Note that the pattern must have been
  318.             parsed by dos.library/ParsePatternNoCase(). Default
  319.             is ~(#?) which matches nothing. (V38)
  320.  
  321.     ASLFR_AcceptPattern (UBYTE *) - Specifies an AmigaDOS pattern that is
  322.             used to accept files. That is, only files with names
  323.             matching this pattern are included in the file list.
  324.             Note that the pattern must have been parsed by
  325.             dos.library/ParsePatternNoCase(). Default is #? which
  326.             matches everything. (V38)
  327.  
  328.     ASLFR_FilterDrawers (BOOL) - Set this tag to TRUE if you want the
  329.             ASLFR_RejectPattern, ASLFR_AcceptPattern, and the
  330.             Pattern text gadget to also apply to drawer names.
  331.             Normally, drawers are always displayed. Default is
  332.             FALSE. (V38)
  333.  
  334.     ASLFR_HookFunc (APTR) - A function that is called if the
  335.             FRF_FILTERFUNC or FRF_INTUIFUNC flags are specified in
  336.             the ASLFR_Flags1 tag. The function will be called like
  337.             so, with the arguments on the stack using the standard
  338.             C pushing order:
  339.  
  340.                 ULONG function(ULONG mask, APTR object,
  341.                            struct FileRequester *fr)
  342.  
  343.             The Mask value is a copy of the specific ASLFR_Flags1
  344.             value the callback is for, either FRF_FILTERFUNC or
  345.             FRF_INTUIFUNC; object is a pointer to a data object
  346.             (a (struct IntuiMessage *) for FRF_INTUIFUNC, and a
  347.             (struct AnchorPath *) for FRF_FILTERFUNC).
  348.  
  349.             For FRF_FILTERFUNC, the function should return 0 if the
  350.             file should be added to the list, non-zero if it
  351.             shouldn't. For FRF_INTUIFUNC, the function should
  352.             return the original (struct IntuiMessage *) it was
  353.             passed.
  354.  
  355.     ASLFR_SetSortBy (ULONG) -- Criteria for sorting the file list.
  356.             this must be one of ASLFRSORTBY_Name (sort by name),
  357.             ASLFRSORTBY_Date (sort by date) or ASLFRSORTBY_Size
  358.             (sort by size).
  359.             Default is ASLFRSORTBY_Name. (V44)
  360.  
  361.     ASLFR_GetSortBy (ULONG *) -- Before leaving AslRequest(), the
  362.             file requester will store its current sort criteria
  363.             (ASLFRSORTBY_Name, ASLFRSORTBY_Date or ASLFRSORTBY_Size)
  364.             in the ULONG pointed to by this tag.
  365.             Default is NULL, i.e. no data is stored. (V44)
  366.  
  367.     ASLFR_SetSortDrawers (ULONG) -- Determines where drawers
  368.             are placed in the sorted list; this must be one of
  369.             ASLFRSORTDRAWERS_First (drawers appear before all
  370.             other files), ASLFRSORTDRAWERS_Mix (drawers are sorted
  371.             along with the the other files) or ASLFRSORTDRAWERS_Last
  372.             (drawers appear after all other files).
  373.             Default is ASLFRSORTDRAWERS_First. (V44)
  374.  
  375.     ASLFR_GetSortDrawers (ULONG *) -- Before leaving AslRequest(),
  376.             the file requester will store its current drawer list
  377.             placement (ASLFRSORTDRAWERS_First, ASLFRSORTDRAWERS_Mix
  378.             or ASLFRSORTDRAWERS_Last) in the ULONG pointed to by
  379.             this tag.
  380.             Default is NULL, i.e. no data is stored. (V44)
  381.  
  382.     ASLFR_SetSortOrder (ULONG) -- Selects the order in which
  383.             the list is sorted; this must be one of ASLFRSORTORDER_Ascend
  384.             (smallest/oldest files first, largest/newest files last)
  385.             or ASLFRSORTORDER_Descend (largest/newest files first,
  386.             smallest/oldest files last).
  387.             Default is ASLFRSORTORDER_Ascend. (V44)
  388.  
  389.     ASLFR_GetSortOrder (ULONG *) -- Before leaving AslRequest(),
  390.             the file requester will store its current sort order
  391.             (ASLFRSORTORDER_Ascend, ASLFRSORTORDER_Descend) in the
  392.             ULONG pointed to by this tag.
  393.             Default is NULL, i.e. no data is stored. (V44)
  394.  
  395.     ASLFR_PopToFront (BOOL) -- When set to TRUE, this tells ASL to
  396.             bring the screen to the front the requester has opened on.
  397.             The position of the screen will be adjusted, too, to bring
  398.             the area into view the window has opened in. The screen
  399.             brought to the front will be pushed into the background
  400.             again when the requester window closes.
  401.             Default is TRUE. (V44)
  402.  
  403.     Tags used for the font requester:
  404.  
  405.     ASLFO_Window (struct Window *) - Parent window of requester. If no
  406.             ASLFO_Screen tag is specified, the window structure
  407.             is used to determine on which screen to open the
  408.             requesting window. (V36)
  409.  
  410.     ASLFO_PubScreenName (STRPTR) - Name of a public screen to open on.
  411.             This overrides the screen used by ASLFO_Window. (V38)
  412.  
  413.     ASLFO_Screen (struct Screen *) - Screen on which to open the requester.
  414.             This overrides the screen used by ASLFO_Window or by
  415.             ASLFO_PubScreenName. (V38)
  416.  
  417.     ASLFO_PrivateIDCMP (BOOL) - When set to TRUE, this tells ASL to
  418.             allocate a new IDCMP port for the requesting window.
  419.             If not specified or set to FALSE, and if ASLFO_Window
  420.             is provided, the requesting window will share
  421.             ASLFO_Window's IDCMP port. (V38)
  422.  
  423.     ASLFO_IntuiMsgFunc (struct Hook *) - A function to call whenever an
  424.             unknown Intuition message arrives at the message port
  425.             being used by the requesting window. The function
  426.             receives the following parameters:
  427.                 A0 - (struct Hook *)
  428.                 A1 - (struct IntuiMessage *)
  429.                 A2 - (struct FontRequester *)
  430.             (V38)
  431.  
  432.     ASLFO_SleepWindow (BOOL) - When set to TRUE, this tag will cause the
  433.             window specified by ASLFO_Window to be "put to
  434.             sleep". That is, a busy pointer will be displayed in
  435.             the parent window, and no gadget or menu activity will
  436.             be allowed. This is done by opening an invisible
  437.             Intuition Requester in the parent window. (V38)
  438.  
  439.     ASLFO_UserData (APTR) - A 32-bit value that is simply copied in the
  440.             fo_UserData field of the requester structure. (V38)
  441.  
  442.     ASLFO_TextAttr (struct TextAttr *) - Font to be used for the requesting
  443.             window's gadgets and menus. If this tag is not provided
  444.             or its value is NULL, the default font of the screen
  445.             on which the requesting window opens will be used.
  446.             This font must already be in memory as ASL calls
  447.             OpenFont() and not OpenDiskFont().
  448.             (V38)
  449.  
  450.     ASLFO_Locale (struct Locale *) - Locale to use for the requesting
  451.             window. This determines the language used for the
  452.             requester's gadgets and menus. If this tag is not
  453.             provided or its value is NULL, the system's current
  454.             default locale will be used. (V38)
  455.  
  456.     ASLFO_TitleText (STRPTR) - Title to use for the requesting window.
  457.             Default is no title. (V36)
  458.  
  459.     ASLFO_PositiveText (STRPTR) - Label of the positive gadget in the
  460.             requester. English default is "OK". Prior to V38, this
  461.             string could not be longer than 6 characters. (V36)
  462.  
  463.     ASLFO_NegativeText (STRPTR) - Label of the negative gadget in the
  464.             requester. English default is "Cancel". Prior to V38,
  465.             this string could not be longer than 6 characters.
  466.             (V36)
  467.  
  468.     ASLFO_InitialLeftEdge (WORD) - Suggested left edge of requesting
  469.             window. (V36)
  470.  
  471.     ASLFO_InitialTopEdge (WORD) - Suggested top edge of requesting
  472.             window. (V36)
  473.  
  474.     ASLFO_InitialWidth (WORD) - Suggested width of requesting window. (V38)
  475.  
  476.     ASLFO_InitialHeight (WORD) - Suggested height of requesting window.
  477.             (V38)
  478.  
  479.     ASLFO_InitialName (STRPTR) - Initial contents of the font requester's
  480.             Name text gadget. Default is none. (V36)
  481.  
  482.     ASLFO_InitialSize (UWORD) - Initial contents of the font requester's
  483.             Size numeric gadget (fo_Attr.ta_YSize). Default is 8.
  484.             (V36)
  485.  
  486.     ASLFO_InitialStyle (UBYTE) - Initial setting of the font requester's
  487.             Style gadget (fo_Attr.ta_Style). Default is FS_NORMAL.
  488.             (V36)
  489.  
  490.     ASLFO_InitialFlags (UBYTE) - Initial setting of the font requester's
  491.             fo_Flags field (fo_Attr.ta_Flags). Default is
  492.             FPF_ROMFONT. (V36)
  493.  
  494.     ASLFO_InitialFrontPen (UBYTE) - Initial setting of the font requester's
  495.             Front Color gadget (fo_FrontPen). This value also
  496.             determines the color used to render the text in the
  497.             sample font area. Default is 1. (V36)
  498.  
  499.     ASLFO_InitialBackPen (UBYTE) - Initial setting of the font requester's
  500.             Back Color gadget (fo_BackPen). This value also
  501.             determines the color used to render the background of
  502.             the sample font area. Default is 0. (V36)
  503.  
  504.     ASLFO_InitialDrawMode (UBYTE) - Initial setting of the font
  505.             requester's Mode gadget (fo_DrawMode). Default is
  506.             JAM1. (V38)
  507.  
  508.     ASLFO_Flags (ULONG) - Bulk initialization of many of the requester's
  509.             options. See <libraries/asl.h> for the possible
  510.             flag values. Default is 0. (V36)
  511.  
  512.     ASLFO_DoFrontPen (BOOL) - Set this tag to TRUE to cause the requester
  513.             to display the Front Color selection gadget. Default is
  514.             FALSE. (V38)
  515.  
  516.     ASLFO_DoBackPen (BOOL) - Set this tag to TRUE to cause the requester
  517.             to display the Back Color selection gadget. Default
  518.             is FALSE. (V38)
  519.  
  520.     ASLFO_DoStyle (BOOL) - Set this tag to TRUE to cause the requester
  521.             to display the Style checkboxes. Default is FALSE.
  522.             (V38)
  523.  
  524.     ASLFO_DoDrawMode (BOOL) - Set this tag to TRUE to cause the requester
  525.             to display the Mode cycle gadget. Default is FALSE.
  526.             (V38)
  527.  
  528.     ASLFO_FixedWidthOnly (BOOL) - Set this tag to TRUE to cause the
  529.             requester to only display fixed-width fonts. Default
  530.             is FALSE. (V38)
  531.  
  532.     ASLFO_MinHeight (UWORD) - The minimum font height to let the user
  533.             select. Default is 5. (V36)
  534.  
  535.     ASLFO_MaxHeight (UWORD) - The maximum font height to let the user
  536.             select. Default is 24. (V36)
  537.  
  538.     ASLFO_FilterFunc (struct Hook *) - A function to call for each font
  539.             encountered. If the function returns TRUE, the font is
  540.             included in the font list, otherwise it is rejected
  541.             and not displayed. The function receives the following
  542.             parameters:
  543.                 A0 - (struct Hook *)
  544.                 A1 - (struct TextAttr *)
  545.                 A2 - (struct FontRequester *)
  546.             (V38)
  547.  
  548.     ASLFO_HookFunc (APTR) - A function that is called if the
  549.             FOF_FILTERFUNC or FOF_INTUIFUNC flags are specified in
  550.             the ASLFO_Flags tag. The function will be called like
  551.             so, with the arguments on the stack using the standard
  552.             C pushing order:
  553.  
  554.                 ULONG function(ULONG mask, APTR object,
  555.                            struct FontRequester *fr)
  556.  
  557.             The Mask value is a copy of the specific ASLFO_Flags
  558.             value the callback is for, either FOF_FILTERFUNC or
  559.             FOF_INTUIFUNC; object is a pointer to a data object
  560.             (a (struct IntuiMessage *) for FOF_INTUIFUNC, and a
  561.             (struct TextAttr *) for FOF_FILTERFUNC).
  562.  
  563.             For FOF_FILTERFUNC, the function should return 1 if the
  564.             font should be added to the list, 0 if it
  565.             shouldn't. For FOF_INTUIFUNC, the function should
  566.             return the original (struct IntuiMessage *) it was
  567.             passed.
  568.  
  569.     ASLFO_MaxFrontPen (UBYTE) - The maximum number of pens that are offered
  570.             to the user when the ASLFO_DoFrontPen tag is specified.
  571.             Default is 255. (V40)
  572.  
  573.     ASLFO_MaxBackPen (UBYTE) - The maximum number of pens that are offered
  574.             to the user when the ASLFO_DoBackPen tag is specified.
  575.             Default is 255. (V40)
  576.  
  577.     ASLFO_ModeList (STRPTR *) - Replacement list of modes to display in
  578.             Mode cycle gadget. The first string pointer is used
  579.             as the name of the gadgets, and following strings are
  580.             used as the different labels of the cycle gadget,
  581.             until a NULL string pointer which denotes the end of
  582.             the string pointer array. The first string in this
  583.             array corresponds to JAM1, the second is JAM2, the
  584.             third to COMPLEMENT. The array can be early terminated
  585.             by not providing all entries. English default for
  586.             the array is "Text" "Text+Field" and "Complement".
  587.             (V36)
  588.  
  589.     ASLFO_FrontPens (UBYTE *) - Pointer to a table of pen numbers
  590.             indicating  which colors should be used and edited
  591.             by the palette gadget when the ASLFO_DoFrontPen tag is
  592.             specified. This array must contain as many entries as
  593.             there are colors displayed in the palette gadget. The
  594.             Default is NULL, which causes a 1-to-1 mapping of pen
  595.             numbers. (V40)
  596.  
  597.     ASLFO_BackPens (UBYTE *) - Pointer to a table of pen numbers
  598.             indicating  which colors should be used and edited
  599.             by the palette gadget when the ASLFO_DoBackPen tag is
  600.             specified. This array must contain as many entries as
  601.             there are colors displayed in the palette gadget. The
  602.             Default is NULL, which causes a 1-to-1 mapping of pen
  603.             numbers. (V40)
  604.  
  605.     ASLFO_PopToFront (BOOL) -- When set to TRUE, this tells ASL to
  606.             bring the screen to the front the requester has opened on.
  607.             The position of the screen will be adjusted, too, to bring
  608.             the area into view the window has opened in. The screen
  609.             brought to the front will be pushed into the background
  610.             again when the requester window closes.
  611.             Default is TRUE. (V44)
  612.  
  613.     Tags used for the screen mode requester (V38):
  614.  
  615.     ASLSM_Window (struct Window *) - Parent window of requester. If no
  616.             ASLSM_Screen tag is specified, the window structure
  617.             is used to determine on which screen to open the
  618.             requesting window. (V38)
  619.  
  620.     ASLSM_PubScreenName (STRPTR) - Name of a public screen to open on.
  621.             This overrides the screen used by ASLSM_Window. (V38)
  622.  
  623.     ASLSM_Screen (struct Screen *) - Screen on which to open the requester.
  624.             This overrides the screen used by ASLSM_Window or by
  625.             ASLSM_PubScreenName. (V38)
  626.  
  627.     ASLSM_PrivateIDCMP (BOOL) - When set to TRUE, this tells ASL to
  628.             allocate a new IDCMP port for the requesting window.
  629.             If not specified or set to FALSE, and if ASLSM_Window
  630.             is provided, the requesting window will share
  631.             ASLSM_Window's IDCMP port. (V38)
  632.  
  633.     ASLSM_IntuiMsgFunc (struct Hook *) - A function to call whenever an
  634.             unknown Intuition message arrives at the message port
  635.             being used by the requesting window. The function
  636.             receives the following parameters:
  637.                 A0 - (struct Hook *)
  638.                 A1 - (struct IntuiMessage *)
  639.                 A2 - (struct ScreenModeRequester *)
  640.             (V38)
  641.  
  642.     ASLSM_SleepWindow (BOOL) - When set to TRUE, this tag will cause the
  643.             window specified by ASLSM_Window to be "put to
  644.             sleep". That is, a busy pointer will be displayed in
  645.             the parent window, and no gadget or menu activity will
  646.             be allowed. This is done by opening an invisible
  647.             Intuition Requester in the parent window. (V38)
  648.  
  649.     ASLSM_UserData (APTR) - A 32-bit value that is simply copied in the
  650.             sm_UserData field of the requester structure. (V38)
  651.  
  652.     ASLSM_TextAttr (struct TextAttr *) - Font to be used for the requesting
  653.             window's gadgets and menus. If this tag is not provided
  654.             or its value is NULL, the default font of the screen
  655.             on which the requesting window opens will be used.
  656.             This font must already be in memory as ASL calls
  657.             OpenFont() and not OpenDiskFont().
  658.             (V38)
  659.  
  660.     ASLSM_Locale (struct Locale *) - Locale to use for the requesting
  661.             window. This determines the language used for the
  662.             requester's gadgets and menus. If this tag is not
  663.             provided or its value is NULL, the system's current
  664.             default locale will be used. (V38)
  665.  
  666.     ASLSM_TitleText (STRPTR) - Title to use for the requesting window.
  667.             Default is no title. (V38)
  668.  
  669.     ASLSM_PositiveText (STRPTR) - Label of the positive gadget in the
  670.             requester. English default is "OK". Prior to V38, this
  671.             string could not be longer than 6 characters. (V36)
  672.  
  673.     ASLSM_NegativeText (STRPTR) - Label of the negative gadget in the
  674.             requester. English default is "Cancel". Prior to V38,
  675.             this string could not be longer than 6 characters.
  676.             (V36)
  677.  
  678.     ASLSM_InitialLeftEdge (WORD) - Suggested left edge of requesting
  679.             window. (V38)
  680.  
  681.     ASLSM_InitialTopEdge (WORD) - Suggested top edge of requesting
  682.             window. (V38)
  683.  
  684.     ASLSM_InitialWidth (WORD) - Suggested width of requesting window. (V38)
  685.  
  686.     ASLSM_InitialHeight (WORD) - Suggested height of requesting window.
  687.             (V38)
  688.  
  689.     ASLSM_InitialDisplayID (ULONG) - Initial setting of the Mode list view
  690.             gadget (sm_DisplayID). Default is 0 (LORES_KEY). (V38)
  691.  
  692.     ASLSM_InitialDisplayWidth (ULONG) - Initial setting of the Width gadget
  693.             (sm_DisplayWidth). Default is 640. (V38)
  694.  
  695.     ASLSM_InitialDisplayHeight (ULONG) - Initial setting of the Height
  696.             gadget (sm_DisplayHeight). Default is 200. (V38)
  697.  
  698.     ASLSM_InitialDisplayDepth (UWORD) - Initial setting of the Colors
  699.             gadget (sm_DisplayDepth). Default is 2. (V38)
  700.  
  701.     ASLSM_InitialOverscanType (UWORD) - Initial setting of the
  702.             Overscan Type cycle gadget (sm_OverscanType).
  703.             These values are the OSCAN_#? values from
  704.             <intuition/screens.h>.
  705.  
  706.             User-space naming of overscan types is different than
  707.             programmer-space:
  708.  
  709.             Under V38:
  710.                  0               -->  "Regular Size"
  711.                  OSCAN_TEXT      -->  "Text Size"
  712.                  OSCAN_STANDARD  -->  "Graphics Size"
  713.                  OSCAN_MAXIMUM   -->  "Maximum Size"
  714.  
  715.             Under V39 and above:
  716.                  OSCAN_TEXT      -->  "Text Size"
  717.                  OSCAN_STANDARD  -->  "Graphics Size"
  718.                  OSCAN_MAXIMUM   -->  "Extreme Size"
  719.                  OSCAN_VIDEO     -->  "Maximum Size"
  720.  
  721.             OSCAN_VIDEO is not supported prior to V39. The value
  722.             0 corresponds to "Regular Size" under V38. Since this
  723.             value isn't supported by Intuition's SA_Overscan
  724.             tag, it was removed from ASL in V39. Asking for 0
  725.             under V39 will yield OSCAN_TEXT.
  726.  
  727.             Default is OSCAN_TEXT. (V38)
  728.  
  729.     ASLSM_InitialAutoScroll (BOOL) - Initial setting of the AutoScroll
  730.             cycle gadget (sm_AutoScroll). Default is TRUE. (V38)
  731.  
  732.     ASLSM_InitialInfoOpened (BOOL) - Whether to open the property
  733.             information window automatically. Default is FALSE.
  734.             (V38)
  735.  
  736.     ASLSM_InitialInfoLeftEdge (WORD) - Initial left edge of information
  737.             window. (V38)
  738.  
  739.     ASLSM_InitialInfoTopEdge (WORD) - Initial top edge of information
  740.             window. (V38)
  741.  
  742.     ASLSM_DoWidth (BOOL) - Set this tag to TRUE to cause the requester
  743.             to display the Width numeric gadget. Default is FALSE.
  744.             (V38)
  745.  
  746.     ASLSM_DoHeight (BOOL) - Set this tag to TRUE to cause the requester
  747.             to display the Height numeric gadget. Default is FALSE.
  748.             (V38)
  749.  
  750.     ASLSM_DoDepth (BOOL) - Set this tag to TRUE to cause the requester to
  751.             display the Colors slider gadget. Default is FALSE.
  752.             (V38)
  753.  
  754.     ASLSM_DoOverscanType (BOOL) - Set this tag to TRUE to cause the
  755.             requester to display the Overscan Type cycle gadget.
  756.             Default is FALSE. (V38)
  757.  
  758.     ASLSM_DoAutoScroll (BOOL) - Set this tag to TRUE to cause the requester
  759.             to display the AutoScroll checkbox gadget. Default is
  760.             FALSE. (V38)
  761.  
  762.     ASLSM_PropertyFlags (ULONG) - A mode must have these property flags to
  763.             appear in the list of modes. Only the bits set in
  764.             ASLSM_PropertyMask are considered. See the description
  765.             of ASLSM_PropertyMask for more info. Default is
  766.             DIPF_IS_WB. (V38)
  767.  
  768.     ASLSM_PropertyMask (ULONG) - A mask to apply to ASLSM_PropertyFlags
  769.             to determine which bits to consider. The use of these
  770.             two values is identical in concept to how Exec uses
  771.             the two flag paraneters in exec.library/SetSignal().
  772.             Default is DIPF_IS_WB. This is how this tag and the
  773.             ASLSM_PropertyFlags tag interact:
  774.  
  775.             if ((displayInfo.PropertyFlags & propertyMask) ==
  776.                (propertyFlags & propertyMask))
  777.             {
  778.                 /* Mode accepted */
  779.             }
  780.             else
  781.             {
  782.                 /* Mode rejected */
  783.             }
  784.  
  785.             where "displayInfo" is a filled in DisplayInfo
  786.             structure for a given mode. (V38)
  787.  
  788.     ASLSM_MinWidth (ULONG) - The minimum display width to let the user
  789.             choose. Default is 16. (V38)
  790.  
  791.     ASLSM_MaxWidth (ULONG) - The maximum display width to let the user
  792.             choose. Default is 16368. (V38)
  793.  
  794.     ASLSM_MinHeight (ULONG) - The minimum display height to let the user
  795.             choose. Default is 16. (V38)
  796.  
  797.     ASLSM_MaxHeight (ULONG) - The maximum display height to let the user
  798.             choose. Default is 16384. (V38)
  799.  
  800.     ASLSM_MinDepth (UWORD) - The minimum display depth to let the user
  801.             choose. Default is 1. (V38)
  802.  
  803.     ASLSM_MaxDepth (UWORD) - The maximum display depth to let the user
  804.             choose. Default is 24. (V38)
  805.  
  806.     ASLSM_FilterFunc (struct Hook *) - A function to call for each mode
  807.             encountered. If the function returns TRUE, the mode is
  808.             included in the file list, otherwise it is rejected
  809.             and not displayed. The function receives the following
  810.             parameters:
  811.                 A0 - (struct Hook *)
  812.                 A1 - (ULONG) mode id
  813.                 A2 - (struct ScreenModeRequester *)
  814.             (V38)
  815.  
  816.     ASLSM_CustomSMList (struct List *) - Custom list of modes to let
  817.             the user choose from. This is a list of DisplayNode
  818.             nodes, see <libraries/asl.h> for the definition. (V38)
  819.  
  820.     ASLSM_PopToFront (BOOL) -- When set to TRUE, this tells ASL to
  821.             bring the screen to the front the requester has opened on.
  822.             The position of the screen will be adjusted, too, to bring
  823.             the area into view the window has opened in. The screen
  824.             brought to the front will be pushed into the background
  825.             again when the requester window closes.
  826.             Default is TRUE. (V44)
  827.  
  828.    RESULT
  829.     result - FALSE if the user cancelled the requester or if something
  830.          prevented the requester from opening. If TRUE, values in the
  831.          requester structure will be set depending on the particular
  832.          type of requester.
  833.  
  834.          Under V38, If the return value is FALSE, you can look
  835.          at the result from the dos.library/IoErr() function to
  836.          determine whether the requester was cancelled or simply
  837.          failed to open. If dos.library/IoErr() returns 0, then the
  838.          requester was cancelled, any other value indicates a failure
  839.          to open. Current possible failure codes are
  840.          ERROR_NO_FREE_STORE which indicates there was not enough
  841.          memory, and ERROR_NO_MORE_ENTRIES which indicates no modes
  842.          were available for display in the screen mode requester
  843.          (usually because the application filter hook filtered them
  844.          all away)
  845.  
  846.    WARNING
  847.     All ASL requester data structures are READ-ONLY and can only be
  848.     modified by using tags!
  849.  
  850.     You must not specify requester options by using both pre-V38
  851.     tags like ASLFR_Flags1 and V38 tags like ASLFR_DoSaveMode as
  852.     this can lead to unexpected results.
  853.  
  854.     Take care when attaching an ASL requester to a simple refresh
  855.     window or a window that already shares its IDCMP with other
  856.     windows. In such cases you must ask for the ASL requester to
  857.     allocate a private IDCMP (with the ASLFR_PrivateIDCMP,
  858.     ASLFO_PrivateIDCMP and ASLSM_PrivateIDCMP tags) or your window
  859.     will lose IDCMP_REFRESHWINDOW events and other messages.
  860.  
  861.    BUGS
  862.     Under V38 and V39, the filtering functions for the file requester
  863.     were only asked to filter drawer selections if the ASLFR_FilterDrawers
  864.     tag was set to TRUE. The compatible behavior, reestablished in V40,
  865.     is to always pass drawers for filtering.
  866.  
  867.    NOTES
  868.     As of V38-V40 the ASL requester uses gadtools.library routines to
  869.     create and maintain its user interface. Every IntuiMessage the library
  870.     passes through the functions specified with ASLSM_IntuiMsgFunc and
  871.     ASLSM_HookFunc will have been filtered through the
  872.     gadtools.library/GT_GetIMsg() routine.
  873.  
  874.    SEE ALSO
  875.     AllocAslRequest(), FreeAslRequest()
  876.  
  877. asl.library/FreeAslRequest                         asl.library/FreeAslRequest
  878.  
  879.    NAME
  880.     FreeAslRequest -- frees resources allocated by AllocAslRequest(). (V36)
  881.  
  882.    SYNOPSIS
  883.     FreeAslRequest(requester);
  884.                A0
  885.  
  886.     VOID FreeAslRequest(APTR);
  887.  
  888.    FUNCTION
  889.     FreeAslRequest() frees any system resources allocated by
  890.     AllocAslRequest(). Once a requester has been freed, it can no
  891.     longer be used with other calls to AslRequest().
  892.  
  893.    INPUTS
  894.     requester - requester obtained from AllocAslRequest(), or NULL in
  895.             which case this function does nothing.
  896.  
  897.    SEE ALSO
  898.     AllocAslRequest()
  899.  
  900. asl.library/FreeFileRequest                       asl.library/FreeFileRequest
  901.  
  902.    NAME
  903.     FreeFileRequest -- free file requester structure. (V36)
  904.  
  905.    SYNOPSIS
  906.     FreeFileRequest(requester);
  907.             A0
  908.  
  909.     VOID FreeFileRequest(struct FileRequester *);
  910.  
  911.    NOTES
  912.     This function is obsolete, please use AllocAslRequest() instead.
  913.  
  914.    SEE ALSO
  915.     FreeAslRequest()
  916.  
  917. asl.library/RequestFile                               asl.library/RequestFile
  918.  
  919.    NAME
  920.     RequestFile -- request user to select files. (V36)
  921.  
  922.    SYNOPSIS
  923.     result = RequestFile(requester);
  924.     D0                   A0
  925.  
  926.     BOOL RequestFile(struct FileRequester *);
  927.  
  928.    NOTES
  929.     This function is obsolete, please use AslRequest() instead.
  930.  
  931.    SEE ALSO
  932.     AslRequest()
  933.  
  934.